Kenyan ID Check API

Objective

The Kenyan ID Check API validates a Kenyan National ID and retrieves detailed information about the corresponding user.

Input	Output
The user's personal details including their national ID number, full name,date of birth and gender	Additional user details. The complete list of output fields is provided under the Success Response Details section.

API Endpoint

kenyanIdCheck

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the complete information on the parameters used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
id	The national ID number	Mandatory	Type: String	Not Applicable
firstName	The first name of the user	Mandatory	Type: String	Not Applicable
lastName	The last name of the user	Mandatory	Type: String	Not Applicable
middleName	The middle name of the user	Optional	Type: String	Not Applicable
dateOfBirth	The date of birth of the user	Mandatory	Type: String Format: YYYY-MM-DD	Not Applicable
gender	The gender of the user	Mandatory	Type: String	Not Applicable

Sample Request

The following code shows a standard cURL request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/kenyanIdCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "id": "<Enter_the_ID_Number>",
    "firstName": "<Enter_the_First_Name>",
    "lastName": "<Enter_the_Last_Name>",
    "middleName": "<Enter_the_Middle_Name>",
    "dateOfBirth": "<Enter_the_Date_of_Birth>",
    "gender": "<Enter_the_Gender>"
}'

Success Response Sample

The following code is a sample of success response from the API.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "entity": {
      "dateOfBirth": "<Date_Of_Birth_in_YYYY-MM-DD_Format>",
      "gender": "<Gender>",
      "expirationDate": "<Expiration_Date>",
      "phoneNumber": "<Phone_Number>",
      "phoneNumber2": "<Secondary_Phone_Number>",
      "address": "<Address_Of_The_User>",
      "secondaryIdNumber": "<Secondary_ID_Number>",
      "placeOfBirth": "<Place_Of_Birth>",
      "firstName": "<First_Name>",
      "serialNumber": "<Serial_Number>",
      "citizenship": "<Citizenship>",
      "dateOfIssue": "<Date_Of_Issue_in_YYYY-MM-DD_Format>",
      "occupation": "<Occupation>",
      "family": "<Family_Details>",
      "middleName": "<Middle_Name>",
      "lastName": "<Last_Name>"
    }
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

Parameter	Type	Description
result.entity.dateOfBirth	string	The date of birth of the user in YYYY-MM-DD format
result.entity.gender	string	The gender of the user
result.entity.expirationDate	string	The expiration date of an identification document or similar item
result.entity.phoneNumber	string	The primary phone number of the user
result.entity.phoneNumber2	string	The secondary phone number of the user
result.entity.address	string	The residential address of the user
result.entity.secondaryIdNumber	string	The unique identifier for the user, possibly a code or ID number
result.entity.placeOfBirth	string	The place where the user was born
result.entity.firstName	string	The first name of the user
result.entity.serialNumber	string	The serial number associated with the user
result.entity.citizenship	string	The Nationality or citizenship status of the user
result.entity.dateOfIssue	string	The date when an identification document or relevant item was issued to the user, in the YYYY-MM-DD format
result.entity.occupation	string	The occupation of the user
result.entity.family	string	The details about the user's family
result.entity.middleName	string	The middle name of the user
result.entity.lastName	string	The last name of the user

Error Response Samples

Invalid ID

{
    "message": "id: Invalid id supplied, ",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId":"<Transaction_ID>"
    }
}

Input Validation Error

{
    "message": "Input Validation Error: DoB should be in YYYY-MM-DD format",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

ID Greater than 8 Digits

{
    "message": "Unable to validate ID",
    "statusCode": 404,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId":"<Transaction_ID>"
    }
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

External Vendor Downtime

{
    "message": "External vendor downtime",
    "statusCode": 503,
    "status": "failure",
    "error": "EXTERNAL_DOWNTIME"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Missing required request parameters	The request has null or undefined input parameters
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
403	Access Denied	Please contact the HyperVerge team for resolution
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	Server Error	Please contact the HyperVerge team for resolution